Introduction
In AndroidLock XT 2.0 it is possible to create custom themes to match your background or Winterboard theme.
Creating new themes is simple and does not require any programming skills, the only needed tools are
an image editor and a text editor.
Theme layout
The first concept to understand about the themes is that the elements are positioned on different layers, as follows:
The first layer is the Background layer, it is provided by the theme and in this example it's empty.
The second layer is the Line layer. It is drawn internally, the theme doesn't need to provide images
for it. The appearance can be costumized by setting the line properties (See theme properties).
The third layer is the Over layer, it is provided by the theme and is placed over the line.
The fourth layer is the Active layer, it is provided by the theme and is shown depending on the user
touch.
The fifth layer is the Direction layer, it is provided by the theme and is the topmost. It is shown
depending on the user touch.
The theme package
A theme is packaged in a directory with a fixed structure:
- Images
- Background.png
- Over.png
- Active.png
- Dir0.png
- Dir1.png
- Dir2.png
- Dir3.png
- Dir4.png
- Dir5.png
- Dir6.png
- Dir7.png
- Info.plist
Here is the description of each file:
| File | Description | Required |
|---|---|---|
| Info.plist | Property list containing the theme title and other settings | Yes |
| Background.png | Image of the Background layer | No |
| Over.png | Image of the Over layer | No |
| Active.png | Image of the Active layer (drawn partially) | No |
| DirX.png | Images of the Direction layer (drawn partially) | No |
The images filenames are intended for normal pixel density devices.
Every theme should include images optimized for iPhone 4 or other future devices with double pixel density,
such images have the same name of the standard resolution wih a "@2x" suffix before the extension.
ie. Background.png and Background@2x.png
If AndroidLock XT can't find the correct image for the device it will try to use the other format and will
scale it automatically.
The images
Full images
The Background and Over images are shown statically and in full size. Their visibility is not affected by the pattern being drawn.
Splitted images
The Active and DirX images are not shown enterily. Those images are divided in 9 pieces, one for each area
that can be touched to compose the pattern.
In the Active image only the piece corresponding to the area being touched is shown. If no point is being touched, no parts of the image appears. This image should be used to highlight the current dot.
The DirX images provide the overlays to indicate the direction of successive dots in a pattern.
If this feature is being used, all of the 8 files must be present, otherwise they will have no effect.
Every image contains the same direction overlay for all the dots, and an image exists for each of the possible
directions:
| Dir0.png | North |
| Dir1.png | North-East |
| Dir2.png | East |
| Dir3.png | South-East |
| Dir4.png | South |
| Dir5.png | South-West |
| Dir6.png | West |
| Dir7.png | North-West |
To create new images, use the doc/reference.png as a reference for the centers and bounds of the touchable areas.
The property list
The Info.plist file contains the configuration for the theme. This file must be edited with a text editor
and NOT with a word processor.
| Section | Name | Description |
|---|---|---|
| Title | The theme's title. This is the text that is shown in the theme picker under Settings. | |
| LineStyle | Color | The line color when the pattern is being drawn. See Color Notes. |
| LineStyle | ColorUnlocked | The line color when the pattern is correct and the device plays the unlock sound. See Color Notes. |
| LineStyle | ColorWrong | The line color when the pattern is wrong. See Color Notes. |
| LineStyle | Width | The line width (in points). |
| LineStyle | Join | The line join style. Possible values are Miter, Bevel and Round. See Quartz 2D Programming Guide to see what they mean. |
| LineStyle | Cap | The line cap style. Possible values are Butt, Square and Round. See Quartz 2D Programming Guide to see what they mean. |
| TextStyle | Color | The color of the text (ie. when the max attempts limit is reached). See Color Notes. |
| Other | AllowDiagonalSegments | Whenever to allow diagonal segments (1) or not (0). |
| Other | ApplyDirectionOverlayInActiveDot | This parameter specifies if the Direction images should be applied to all the pattern nodes except the last (0), like in the original Android lock, or only in the last node (1). |
| Other | KeepShowingLastDotAsActive | Whenever to keep showing the last dot of the pattern as still active when finished to draw the pattern (1) or not (0). |
Almost every image editor will show you the hexadecimal value of a color in the color picker.
The value must be entered without the # prefix. In this format 6 digits must be specified.
ie.
RED is FF0000
BLUE is 0000FF
It is also possible to define a third component, the Alpha, that specifies how much opaque the color is.
In this case a total of 8 digits must be specified.
ie.
RED 50% is FF00007F
BLUE 20% is 0000FF33
Packaging the theme
To create redistributable theme packages you basically have to create a Debian package which installs your theme directory in /var/mobile/Library/AndroidLock/Themes.
Examples
AndroidLock XT 2.0 includes some Themes which use different configurations and can be used as reference.